Wheel-Distributionsformat: Erstellen von Binärpaketen für Python

Das Python-Ökosystem ist stark auf effizientes Paketmanagement angewiesen. Einer der Eckpfeiler dieses Ökosystems ist das Wheel-Distributionsformat, das oft durch die .whl-Erweiterung identifiziert wird. Dieser Leitfaden befasst sich mit den Feinheiten des Wheel-Formats, seinen Vorteilen und wie man Binärpakete für Python erstellt, um Entwickler weltweit zu unterstützen, die eine reibungslose und zuverlässige Softwareverteilung anstreben.

Was ist das Wheel-Format?

Das Wheel-Format ist ein vorkompiliertes Paketformat für Python. Es ist darauf ausgelegt, einfacher zu installieren zu sein als Quellcode-Distributionen (sdist). Es ersetzt das ältere Egg-Format und behebt mehrere seiner Mängel. Im Wesentlichen handelt es sich um ein ZIP-Archiv mit einer bestimmten Struktur und Metadaten, das es pip und anderen Installationswerkzeugen ermöglicht, das Paket schnell zu installieren, ohne es aus dem Quellcode kompilieren zu müssen.

Schlüsselmerkmale von Wheel

• Plattformunabhängigkeit (wo zutreffend): Wheels können für spezifische Plattformen und Architekturen (z. B. Windows 64-Bit, Linux x86_64) oder plattformunabhängig (reines Python) erstellt werden. Dies ermöglicht die Erstellung optimierter Binärdateien für verschiedene Betriebssysteme.
• Einfache Installation: Das Wheel-Format enthält vorkompilierte Distributionen, wodurch die Notwendigkeit der Kompilierung von Code während der Installation minimiert wird. Dies beschleunigt den Installationsprozess erheblich, insbesondere für Pakete mit C-Erweiterungen oder anderen kompilierten Komponenten.
• Metadateneinbeziehung: Wheels enthalten alle notwendigen Metadaten über das Paket, einschließlich Abhängigkeiten, Versionsinformationen und Einstiegspunkten. Diese Metadaten sind entscheidend dafür, dass Paketmanager wie pip Abhängigkeiten verwalten und das Paket korrekt installieren können.
• Atomare Installation: pip installiert Pakete aus Wheels atomar. Das bedeutet, dass die Installation entweder erfolgreich abgeschlossen wird oder vollständig rückgängig gemacht wird, wodurch teilweise installierte Pakete vermieden werden, die zu Inkonsistenzen führen können.
• Reproduzierbarkeit: Wheels verbessern die Reproduzierbarkeit, indem sie ein konsistentes Build-Artefakt bereitstellen, das über mehrere Umgebungen hinweg installiert werden kann, ohne dass eine Neukompilierung erforderlich ist (vorausgesetzt, die Zielplattform stimmt überein).

Warum Wheels verwenden?

Die Wahl von Wheels gegenüber Quellcode-Distributionen bietet zahlreiche Vorteile, die den Prozess der Paketinstallation und -bereitstellung optimieren. Hier ist eine Aufschlüsselung der wichtigsten Vorteile:

Schnellere Installationszeiten

Einer der bedeutendsten Vorteile von Wheels ist ihre Geschwindigkeit. Durch die Bereitstellung vorkompilierter Distributionen entfällt die Notwendigkeit, Code während der Installation zu kompilieren. Dies ist besonders vorteilhaft für Pakete mit kompilierten Erweiterungen, die in C, C++ oder anderen Sprachen geschrieben sind. Stellen Sie sich vor, Sie stellen eine komplexe wissenschaftliche Bibliothek bereit; die Verwendung eines Wheels reduziert die Einrichtungszeit auf den Rechnern der Endbenutzer drastisch.

Beispiel: Die Installation von numpy aus dem Quellcode kann mehrere Minuten dauern, insbesondere auf älterer Hardware. Die Installation aus einem Wheel dauert in der Regel Sekunden.

Reduzierte Abhängigkeit von Build-Tools

Die Installation von Paketen aus dem Quellcode erfordert oft, dass Benutzer die notwendigen Build-Tools (Compiler, Header usw.) auf ihrem System installiert haben. Dies kann eine Eintrittsbarriere darstellen, insbesondere für Benutzer, die nicht mit der Softwareentwicklung vertraut sind. Wheels beseitigen diese Abhängigkeit und machen die Installation einfacher und zugänglicher.

Beispiel: Ein Datenwissenschaftler in einem Forschungslabor verfügt möglicherweise nicht über die notwendigen Compiler, um ein Paket aus dem Quellcode zu erstellen. Ein Wheel ermöglicht es ihm, das Paket direkt zu installieren, ohne seine Umgebung konfigurieren zu müssen.

Verbesserte Zuverlässigkeit

Durch die Bereitstellung vorkompilierter Binärdateien stellen Wheels sicher, dass das Paket in verschiedenen Umgebungen konsistent installiert wird. Dies reduziert das Risiko von Installationsfehlern aufgrund von Unterschieden in den Systemkonfigurationen oder Build-Tool-Versionen. Diese Konsistenz ist für Anwendungen, die ein stabiles und vorhersehbares Verhalten erfordern, von größter Bedeutung.

Beispiel: Eine Webanwendung, die auf mehreren Servern bereitgestellt wird, muss konsistente Paketversionen haben. Die Verwendung von Wheels stellt sicher, dass auf jedem Server dieselben Binärdateien installiert werden, was das Risiko von Bereitstellungsproblemen minimiert.

Erhöhte Sicherheit

Wheels können signiert werden, um ihre Authentizität und Integrität zu überprüfen. Dies hilft zu verhindern, dass böswillige Akteure manipulierte Pakete verteilen. Die Paketunterschrift bietet eine zusätzliche Sicherheitsebene und stellt sicher, dass Benutzer vertrauenswürdige Software installieren.

Beispiel: Organisationen können Richtlinien implementieren, die verlangen, dass alle Pakete signiert werden, bevor sie in Produktionsumgebungen bereitgestellt werden. Dies schützt vor Angriffen auf die Lieferkette, bei denen bösartiger Code in Pakete injiziert wird.

Erstellen von Wheel-Paketen: Eine Schritt-für-Schritt-Anleitung

Das Erstellen von Wheel-Paketen ist ein unkomplizierter Prozess, der die Pakete setuptools und wheel verwendet. Hier ist eine detaillierte Anleitung:

1. Einrichten Ihres Projekts

Stellen Sie zunächst sicher, dass Ihr Projekt richtig strukturiert ist. Sie benötigen mindestens eine setup.py-Datei und den Quellcode Ihres Pakets.

Beispiel für Projektstruktur:

my_package/
 ├── my_module/
 │   ├── __init__.py
 │   └── my_function.py
 ├── setup.py
 └── README.md

2. Die Datei setup.py

Die Datei setup.py ist das Herzstück Ihres Projekts. Sie enthält die Metadaten zu Ihrem Paket und definiert, wie es erstellt und installiert werden soll. Hier ist ein Beispiel für eine setup.py-Datei:

from setuptools import setup, find_packages

setup(
 name='my_package',
 version='0.1.0',
 description='Ein einfaches Beispielpaket',
 long_description=open('README.md').read(),
 long_description_content_type='text/markdown',
 url='https://github.com/your_username/my_package',
 author='Your Name',
 author_email='your.email@example.com',
 license='MIT',
 packages=find_packages(),
 install_requires=['requests'],
 classifiers=[
 'Development Status :: 3 - Alpha',
 'Intended Audience :: Developers',
 'License :: OSI Approved :: MIT License',
 'Programming Language :: Python :: 3',
 'Programming Language :: Python :: 3.6',
 'Programming Language :: Python :: 3.7',
 'Programming Language :: Python :: 3.8',
 'Programming Language :: Python :: 3.9',
 ],
)

Erläuterung der wichtigsten Felder:

• name: Der Name Ihres Pakets. Dies ist der Name, den Benutzer zur Installation Ihres Pakets verwenden (z. B. pip install my_package).
• version: Die Versionsnummer Ihres Pakets. Befolgen Sie die semantische Versionierung (SemVer) für konsistente Versionspraktiken (z. B. 0.1.0, 1.0.0, 2.5.1).
• description: Eine kurze Beschreibung Ihres Pakets.
• long_description: Eine detaillierte Beschreibung Ihres Pakets. Diese wird oft aus einer README.md-Datei gelesen.
• url: Die URL der Homepage oder des Repositories Ihres Pakets.
• author: Der Name des Paketautors.
• author_email: Die E-Mail-Adresse des Paketautors.
• license: Die Lizenz, unter der Ihr Paket vertrieben wird (z. B. MIT, Apache 2.0, GPL).
• packages: Eine Liste von Paketen, die in Ihre Distribution aufgenommen werden sollen. find_packages() findet automatisch alle Pakete in Ihrem Projekt.
• install_requires: Eine Liste von Abhängigkeiten, die Ihr Paket benötigt. pip installiert diese Abhängigkeiten automatisch, wenn Ihr Paket installiert wird.
• classifiers: Metadaten, die Benutzern helfen, Ihr Paket im PyPI (Python Package Index) zu finden. Diese Klassifizierungen beschreiben den Entwicklungsstatus, die Zielgruppe, die Lizenz und die unterstützten Python-Versionen.

3. Installation von wheel

Wenn Sie das wheel-Paket nicht installiert haben, können Sie es mit pip installieren:

pip install wheel

4. Erstellen des Wheel-Pakets

Navigieren Sie zum Stammverzeichnis Ihres Projekts (wo sich setup.py befindet) und führen Sie den folgenden Befehl aus:

python setup.py bdist_wheel

Dieser Befehl erstellt ein dist-Verzeichnis, das das Wheel-Paket (.whl-Datei) und eine Quellcode-Distribution (.tar.gz-Datei) enthält.

5. Lokalisieren der Wheel-Datei

Die generierte Wheel-Datei befindet sich im Verzeichnis dist. Ihr Name folgt dem Format package_name-version-pyXX-none-any.whl, wobei:

• package_name: Der Name Ihres Pakets.
• version: Die Versionsnummer Ihres Pakets.
• pyXX: Die Python-Version, mit der das Paket kompatibel ist (z. B. py37 für Python 3.7).
• none: Zeigt an, dass das Paket nicht plattformspezifisch ist.
• any: Zeigt an, dass das Paket mit jeder Architektur kompatibel ist.

Bei plattformspezifischen Wheels werden die Tags none und any durch Plattform- und Architekturidentifikatoren ersetzt (z. B. win_amd64 für Windows 64-Bit).

6. Testen des Wheel-Pakets

Bevor Sie Ihr Wheel-Paket verteilen, ist es wichtig, es zu testen, um sicherzustellen, dass es korrekt installiert wird. Dies können Sie mit pip tun:

pip install dist/my_package-0.1.0-py39-none-any.whl

Ersetzen Sie dist/my_package-0.1.0-py39-none-any.whl durch den tatsächlichen Pfad zu Ihrer Wheel-Datei.

7. Verteilen Ihres Wheel-Pakets

Nachdem Sie Ihr Wheel-Paket erstellt und getestet haben, können Sie es über verschiedene Kanäle verteilen:

• PyPI (Python Package Index): Der gängigste Weg, Python-Pakete zu verteilen. Sie können Ihr Wheel-Paket mit twine auf PyPI hochladen.
• Privater Paketindex: Für den internen Gebrauch innerhalb einer Organisation können Sie einen privaten Paketindex mit Tools wie devpi oder Artifactory einrichten.
• Direkte Verteilung: Sie können Ihr Wheel-Paket auch direkt an Benutzer per E-Mail, Filesharing oder andere Mittel verteilen.

Umgang mit C-Erweiterungen und plattformspezifischen Wheels

Das Erstellen plattformspezifischer Wheels, insbesondere solcher, die C-Erweiterungen enthalten, erfordert zusätzliche Schritte. Hier ist ein Überblick über den Prozess:

1. Kompilieren von C-Erweiterungen

C-Erweiterungen müssen für jede Zielplattform kompiliert werden. Dies beinhaltet typischerweise die Verwendung eines C-Compilers (z. B. GCC, MSVC) und plattformspezifischer Build-Tools.

Beispiel: Unter Windows müssen Sie den Microsoft Visual C++-Compiler verwenden, um C-Erweiterungen zu erstellen. Unter Linux verwenden Sie typischerweise GCC.

2. Verwendung von cffi oder Cython

Tools wie cffi und Cython können den Prozess der Erstellung von C-Erweiterungen vereinfachen. cffi ermöglicht es Ihnen, C-Code direkt aus Python aufzurufen, ohne selbst C-Code schreiben zu müssen, während Cython es Ihnen ermöglicht, C-ähnlichen Code zu schreiben, der in C-Erweiterungen kompiliert wird.

3. Definieren plattformspezifischer Abhängigkeiten

In Ihrer setup.py-Datei können Sie plattformspezifische Abhängigkeiten mit den Parametern setup_requires und install_requires definieren. Dies ermöglicht es Ihnen, unterschiedliche Abhängigkeiten für verschiedene Plattformen anzugeben.

Beispiel:

from setuptools import setup, Extension
import platform

if platform.system() == 'Windows':
 extra_compile_args = ['/O2', '/EHsc']
else:
 extra_compile_args = ['-O3']

setup(
 name='my_package',
 version='0.1.0',
 ext_modules=[
 Extension(
 'my_package.my_extension',
 ['my_package/my_extension.c'],
 extra_compile_args=extra_compile_args,
 ),
 ],
)

4. Erstellen plattformspezifischer Wheels

Um plattformspezifische Wheels zu erstellen, benötigen Sie die entsprechende Build-Umgebung für jede Zielplattform. Dies kann die Verwendung von virtuellen Maschinen oder Virtualisierungstechnologien wie Docker beinhalten.

Beispiel: Um ein Wheel für Windows 64-Bit zu erstellen, müssen Sie den Build-Prozess auf einem Windows 64-Bit-System mit installiertem Microsoft Visual C++-Compiler ausführen.

Best Practices für die Erstellung von Wheel-Paketen

Die Einhaltung von Best Practices stellt sicher, dass Ihre Wheel-Pakete zuverlässig, wartbar und einfach zu verwenden sind. Hier sind einige wichtige Empfehlungen:

1. Verwenden Sie semantische Versionierung (SemVer)

Befolgen Sie die semantische Versionierung (SemVer) für konsistente Versionspraktiken. SemVer verwendet eine dreiteilige Versionsnummer (MAJOR.MINOR.PATCH), um die Art der Änderungen in jeder Version anzugeben.

• MAJOR: Zeigt inkompatible API-Änderungen an.
• MINOR: Zeigt neue Funktionen an, die abwärtskompatibel sind.
• PATCH: Zeigt Fehlerbehebungen an, die abwärtskompatibel sind.

Beispiel: Das Ändern von Parametern einer Funktion auf eine Weise, die den bestehenden Code bricht, würde eine Hauptversionserhöhung erfordern (z. B. von 1.0.0 auf 2.0.0). Das Hinzufügen einer neuen Funktion ohne Änderung bestehender Funktionen würde eine Nebenversionserhöhung erfordern (z. B. von 1.0.0 auf 1.1.0). Die Behebung eines Fehlers würde eine Patch-Versionserhöhung erfordern (z. B. von 1.0.0 auf 1.0.1).

2. Fügen Sie eine README.md-Datei hinzu

Fügen Sie eine README.md-Datei hinzu, die eine detaillierte Beschreibung Ihres Pakets enthält, einschließlich Installationsanweisungen, Anwendungsbeispielen und Beitragsrichtlinien. Dies hilft Benutzern zu verstehen, wie sie Ihr Paket verwenden können, und fördert Beiträge.

3. Schreiben Sie klare und prägnante Dokumentation

Schreiben Sie eine klare und prägnante Dokumentation für Ihr Paket, einschließlich API-Dokumentation, Tutorials und Beispielen. Verwenden Sie Tools wie Sphinx oder Read the Docs, um Dokumentation aus Ihren Code-Kommentaren zu generieren.

4. Verwenden Sie eine Lizenz

Wählen Sie eine Lizenz für Ihr Paket, die klar die Bedingungen festlegt, unter denen es verwendet, geändert und verteilt werden kann. Gängige Lizenzen sind MIT, Apache 2.0 und GPL.

5. Testen Sie Ihr Paket gründlich

Testen Sie Ihr Paket gründlich mit automatisierten Testtools wie pytest oder unittest. Schreiben Sie Unit-Tests, Integrationstests und End-to-End-Tests, um sicherzustellen, dass Ihr Paket in verschiedenen Szenarien korrekt funktioniert.

6. Verwenden Sie Continuous Integration (CI)

Verwenden Sie Continuous Integration (CI)-Tools wie GitHub Actions, GitLab CI oder Jenkins, um Ihr Paket automatisch zu erstellen und zu testen, wann immer Änderungen am Code vorgenommen werden. Dies hilft, Fehler frühzeitig zu erkennen und stellt sicher, dass Ihr Paket immer in einem funktionierenden Zustand ist.

7. Signieren Sie Ihre Pakete

Signieren Sie Ihre Pakete, um ihre Authentizität und Integrität zu überprüfen. Dies hilft, böswillige Akteure davon abzuhalten, manipulierte Pakete zu verteilen. Verwenden Sie Tools wie gpg oder keyring, um Ihre Pakete zu signieren.

Fortgeschrittene Wheel-Techniken

Für fortgeschrittenere Anwendungsfälle sollten Sie diese Techniken in Betracht ziehen:

1. Verwendung von build

Das Paket build bietet eine moderne und standardisierte Möglichkeit zum Erstellen von Python-Paketen. Es unterstützt sowohl Wheels als auch Quellcode-Distributionen und bietet eine einfachere Schnittstelle als setuptools.

pip install build
python -m build

2. Editierbare Installationen

Editierbare Installationen ermöglichen es Ihnen, ein Paket so zu installieren, dass es direkt auf den Quellcode verweist. Dies ist für die Entwicklung nützlich, da Änderungen am Quellcode sofort im installierten Paket reflektiert werden, ohne dass es neu installiert werden muss.

pip install -e .

3. Anpassen des Build-Prozesses

Sie können den Build-Prozess anpassen, indem Sie benutzerdefinierte Build-Skripte definieren oder Build-Systeme wie Meson oder CMake verwenden. Dies ermöglicht es Ihnen, komplexere Build-Szenarien zu handhaben, wie z. B. das Erstellen von C-Erweiterungen mit spezifischen Compiler-Flags oder die Verknüpfung mit externen Bibliotheken.

4. Verwendung von auditwheel

Das Tool auditwheel wird verwendet, um Linux-Wheels zu überprüfen und zu reparieren, die gemeinsam genutzte Bibliotheken enthalten. Es stellt sicher, dass das Wheel alle erforderlichen Abhängigkeiten enthält, um auf einer Vielzahl von Linux-Distributionen ausgeführt zu werden.

pip install auditwheel
auditwheel repair dist/my_package-0.1.0-py39-linux_x86_64.whl

Fazit

Das Wheel-Distributionsformat ist ein wesentliches Werkzeug für Python-Entwickler, die eine effiziente, zuverlässige und sichere Paketverteilung anstreben. Indem Sie die in diesem Leitfaden beschriebenen Schritte befolgen und Best Practices anwenden, können Sie Wheel-Pakete erstellen, die den Installationsprozess optimieren, die Abhängigkeiten von Build-Tools reduzieren und das allgemeine Benutzererlebnis verbessern. Egal, ob Sie Pakete für die Open-Source-Community verteilen oder interne Anwendungen bereitstellen, das Verständnis und die Nutzung des Wheel-Formats sind eine wertvolle Fähigkeit für jeden Python-Entwickler. Da sich Python weiterentwickelt, stellt die Übernahme moderner Paketierungspraktiken wie Wheel sicher, dass Ihre Projekte für ein globales Publikum zugänglich und wartbar bleiben.

Durch die Übernahme dieser Praktiken tragen Sie zu einem robusteren und zugänglicheren Python-Ökosystem weltweit bei.